package com.tianji.promotion.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.tianji.common.domain.dto.PageDTO;
import com.tianji.promotion.domain.dto.CouponFormDTO;
import com.tianji.promotion.domain.dto.CouponIssueFormDTO;
import com.tianji.promotion.domain.po.Coupon;
import com.tianji.promotion.domain.query.CouponQuery;
import com.tianji.promotion.domain.vo.CouponDetailVO;
import com.tianji.promotion.domain.vo.CouponPageVO;
import com.tianji.promotion.domain.vo.CouponVO;

import java.util.List;

/**
 * <p>
 * 优惠券的规则信息 服务类
 * </p>
 *
 * @author zr
 * @since 2024-07-30
 */
public interface ICouponService extends IService<Coupon> {

    /**
     * 保存优惠券信息。
     * <p>
     * 该方法接收一个CouponFormDTO对象作为参数，用于存储优惠券的相关信息。
     * 通过此方法，可以方便地保存用户领取的优惠券或者商家发布的优惠券信息。
     *
     * @param dto 一个CouponFormDTO对象，包含了需要保存的优惠券的所有信息。
     */
    void saveCoupon(CouponFormDTO dto);

    /**
     * 分页查询优惠券信息。
     * <p>
     * 通过CouponQuery参数进行条件查询，返回分页结果，包含优惠券的详细信息。
     * 此方法是系统中查询优惠券信息的核心接口，用于支持前端页面的分页查询功能。
     *
     * @param query 查询条件对象，包含页码、每页数量以及各种过滤条件。
     * @return 返回分页查询结果，包含查询到的优惠券信息和分页相关数据。
     */
    PageDTO<CouponPageVO> queryCouponByPage(CouponQuery query);

    /**
     * 根据优惠券ID查询优惠券详情。
     * <p>
     * 本方法通过调用数据库查询接口，根据提供的优惠券ID，检索出相应的优惠券详细信息。
     * 主要用于前在后台管理中进行优惠券查询操作。
     *
     * @param id 优惠券的唯一标识ID。此ID用于在数据库中定位特定的优惠券记录。
     * @return CouponDetailVO 返回一个包含优惠券详细信息的视图对象。如果找不到对应的优惠券，则返回null。
     */
    CouponDetailVO queryCouponById(Long id);

    /**
     * 开始发行优惠券
     * <p>
     * 该方法用于启动优惠券的发行流程。通过接收一个包含优惠券发行信息的数据传输对象（DTO），
     * 对优惠券的发行进行初始化设置和状态更新。
     *
     * @param dto 优惠券发行表单的DTO，包含了发起优惠券发行所需的所有信息.
     */
    void beginIssue(CouponIssueFormDTO dto);

    /**
     * 暂停发放优惠券
     * <p>
     * 此方法用于暂停发放优惠券。通过指定问题的ID，可以将优惠劵状态标记为暂停，
     *
     * @param id 问题的唯一标识符，用于确定要操作的问题实体
     */
    void pauseIssue(Long id);

    /**
     * 根据指定的ID删除优惠券
     *
     * @param id 要删除的优惠券的唯一标识符
     */
    void deleteById(Long id);

    /**
     * 更新优惠券信息
     * <p>
     * 本函数负责根据提供的优惠券ID更新优惠券的相关信息它使用提供的DTO对象来获取更新的值，
     * 并将这些值应用于数据库中的优惠券记录此操作通常涉及对现有优惠券数据的修改，
     *
     * @param dto 包含要更新的优惠券信息的DTO（数据传输对象）通过这个DTO，
     *            可以获取到更新优惠券所需的所有信息
     * @param id  需要更新的优惠券的唯一标识符通过这个ID可以准确定位到数据库中的具体优惠券记录
     */
    void updateCoupon(CouponFormDTO dto, Long id);

    /**
     * 开始一批优惠券的发放流程
     * <p>
     * 此方法负责启动一批优惠券的发放流
     *
     * @param records 待发放的优惠券记录列表
     *                该列表包含了所有待开始发放的优惠券信息，包括优惠券的详细信息和状态
     */
    void beginIssueBatch(List<Coupon> records);

    /**
     * 结束一批优惠券的发放流程
     * <p>
     * 此方法负责结束一批优惠券的发放流
     *
     * @param records 在截止的优惠券记录列表
     *                该列表包含了所有截止的优惠券信息，包括优惠券的详细信息和状态
     */
    void endIssueBatch(List<Coupon> records);

    /**
     * 查询已发行的优惠券列表
     * <p>
     * 此方法用于从数据库中检索所有已发行的优惠券信息，并将它们封装到CouponVO对象的列表中返回
     * 使用CouponVO对象而非直接使用Coupon实体是为了在展示给用户时可以更加灵活地控制展示信息
     *
     * @return List<CouponVO> 返回一个List对象，其中包含了所有已发行优惠券的CouponVO对象
     */
    List<CouponVO> queryIssuingCoupons();

}
